home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 April: Mac OS SDK / Dev.CD Apr 00 SDK1.toast / Development Kits / Hardware / PowerManager DDK 1.0f1 / Interfaces&Libraries / Interfaces / NameRegistry.h < prev    next >
Encoding:
C/C++ Source or Header  |  1999-10-08  |  16.9 KB  |  556 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        NameRegistry.h
  3.  
  4.      Contains:    NameRegistry Interfaces
  5.  
  6.      Version:    MacOS
  7.  
  8.      DRI:        Bill Galcher
  9.  
  10.      Copyright:    © 1993-1999 by Apple Computer, Inc., all rights reserved.
  11.  
  12.      Warning:    *** APPLE INTERNAL USE ONLY ***
  13.                  This file may contain unreleased API's
  14.  
  15.      BuildInfo:    Built by:            Scott Johnson
  16.                  On:                    10/8/99 11:26 AM
  17.                  With Interfacer:    3.0d13   (MPW PowerPC)
  18.                  From:                NameRegistry.i
  19.                      Revision:        44
  20.                      Dated:            4/8/99
  21.                      Last change by:    BG
  22.                      Last comment:    Now that there is a version number in here, bump it so that we
  23.  
  24.      Bugs:        Report bugs to Radar component "System Interfaces", "Latest"
  25.                  List the version information (from above) in the Problem Description.
  26.  
  27. */
  28. #ifndef __NAMEREGISTRY__
  29. #define __NAMEREGISTRY__
  30.  
  31. #ifndef __MACTYPES__
  32. #include <MacTypes.h>
  33. #endif
  34.  
  35.  
  36.  
  37.  
  38. #if PRAGMA_ONCE
  39. #pragma once
  40. #endif
  41.  
  42. #ifdef __cplusplus
  43. extern "C" {
  44. #endif
  45.  
  46. #if PRAGMA_IMPORT
  47. #pragma import on
  48. #endif
  49.  
  50. #if PRAGMA_STRUCT_ALIGN
  51.     #pragma options align=power
  52. #elif PRAGMA_STRUCT_PACKPUSH
  53.     #pragma pack(push, 2)
  54. #elif PRAGMA_STRUCT_PACK
  55.     #pragma pack(2)
  56. #endif
  57.  
  58. /*******************************************************************************
  59.  * 
  60.  * Foundation Types
  61.  *
  62.  */
  63. /* Value of a property */
  64. typedef void *                            RegPropertyValue;
  65. /* Length of property value */
  66. typedef UInt32                             RegPropertyValueSize;
  67. /*******************************************************************************
  68.  * 
  69.  * RegEntryID    :    The Global x-Namespace Entry Identifier
  70.  *
  71.  */
  72. typedef struct OpaqueDeviceNodePtr*     DeviceNodePtr;
  73.  
  74. struct RegEntryID {
  75.     unsigned short                     es_ver;
  76.     unsigned short                     es_gen;
  77.     DeviceNodePtr                     es_devid;
  78.     unsigned long                     es_spare1;
  79.     unsigned long                     es_spare2;
  80. };
  81. typedef struct RegEntryID                RegEntryID;
  82. typedef RegEntryID *                    RegEntryIDPtr;
  83. /*    
  84.     For Copland, RegEntryID was renamed RegEntryRef.  Add typedef in case
  85.     any source code switched to use the new name.
  86. */
  87.  
  88. typedef RegEntryID                         RegEntryRef;
  89. /*******************************************************************************
  90.  *
  91.  * Root Entry Name Definitions    (Applies to all Names in the RootNameSpace)
  92.  *
  93.  *    • Names are a colon-separated list of name components.  Name components
  94.  *      may not themselves contain colons.  
  95.  *    • Names are presented as null-terminated ASCII character strings.
  96.  *    • Names follow similar parsing rules to Apple file system absolute
  97.  *      and relative paths.  However the '::' parent directory syntax is
  98.  *      not currently supported.
  99.  */
  100. /* Max length of Entry Name */
  101. enum {
  102.     kRegCStrMaxEntryNameLength    = 47
  103. };
  104.  
  105. /* Entry Names are single byte ASCII */
  106. typedef char                             RegCStrEntryName;
  107. typedef char *                            RegCStrEntryNamePtr;
  108. /* length of RegCStrEntryNameBuf =  kRegCStrMaxEntryNameLength+1*/
  109. typedef char                             RegCStrEntryNameBuf[48];
  110. typedef char                             RegCStrPathName;
  111. typedef UInt32                             RegPathNameSize;
  112. enum {
  113.     kRegPathNameSeparator        = ':',                            /* 0x3A */
  114.     kRegEntryNameTerminator        = 0x00,                            /* '\0' */
  115.     kRegPathNameTerminator        = 0x00                            /* '\0' */
  116. };
  117.  
  118. /*******************************************************************************
  119.  *
  120.  * Property Name and ID Definitions
  121.  *    (Applies to all Properties Regardless of NameSpace)
  122.  */
  123. enum {
  124.     kRegMaximumPropertyNameLength = 31,                            /* Max length of Property Name */
  125.     kRegPropertyNameTerminator    = 0x00                            /* '\0' */
  126. };
  127.  
  128. typedef char                             RegPropertyNameBuf[32];
  129. typedef char                             RegPropertyName;
  130. typedef char *                            RegPropertyNamePtr;
  131. enum {
  132.     kRegMaxPropertyNameLength    = kRegMaximumPropertyNameLength
  133. };
  134.  
  135. /*******************************************************************************
  136.  *
  137.  * Iteration Operations
  138.  *
  139.  *    These specify direction when traversing the name relationships
  140.  */
  141. typedef UInt32                             RegIterationOp;
  142. typedef RegIterationOp                     RegEntryIterationOp;
  143. enum {
  144.                                                                 /* Absolute locations*/
  145.     kRegIterRoot                = 0x00000002,                    /* "Upward" Relationships    */
  146.     kRegIterParents                = 0x00000003,                    /* include all  parent(s) of entry */
  147.                                                                 /* "Downward" Relationships*/
  148.     kRegIterChildren            = 0x00000004,                    /* include all children */
  149.     kRegIterSubTrees            = 0x00000005,                    /* include all sub trees of entry */
  150.     kRegIterDescendants            = 0x00000005,                    /* include all descendants of entry */
  151.                                                                 /* "Horizontal" Relationships    */
  152.     kRegIterSibling                = 0x00000006,                    /* include all siblings */
  153.                                                                 /* Keep doing the same thing*/
  154.     kRegIterContinue            = 0x00000001
  155. };
  156.  
  157. /*******************************************************************************
  158.  *
  159.  * Name Entry and Property Modifiers
  160.  *
  161.  *
  162.  *
  163.  * Modifiers describe special characteristics of names
  164.  * and properties.  Modifiers might be supported for
  165.  * some names and not others.
  166.  * 
  167.  * Device Drivers should not rely on functionality
  168.  * specified as a modifier.
  169.  */
  170. typedef UInt32                             RegModifiers;
  171. typedef RegModifiers                     RegEntryModifiers;
  172. typedef RegModifiers                     RegPropertyModifiers;
  173. enum {
  174.     kRegNoModifiers                = 0x00000000,                    /* no entry modifiers in place */
  175.     kRegUniversalModifierMask    = 0x0000FFFF,                    /* mods to all entries */
  176.     kRegNameSpaceModifierMask    = 0x00FF0000,                    /* mods to all entries within namespace */
  177.     kRegModifierMask            = (long)0xFF000000                /* mods to just this entry */
  178. };
  179.  
  180. /* Universal Property Modifiers */
  181. enum {
  182.     kRegPropertyValueIsSavedToNVRAM = 0x00000020,                /* property is non-volatile (saved in NVRAM) */
  183.     kRegPropertyValueIsSavedToDisk = 0x00000040                    /* property is non-volatile (saved on disk) */
  184. };
  185.  
  186. /* NameRegistry version, Gestalt/PEF-style -- MUST BE KEPT IN SYNC WITH MAKEFILE !! */
  187. enum {
  188.     LatestNR_PEFVersion            = 0x01030000                    /* latest NameRegistryLib version (Gestalt/PEF-style) */
  189. };
  190.  
  191. /* ///////////////////////
  192. //
  193. // The Registry API
  194. //
  195. /////////////////////// */
  196. /* NameRegistry dispatch indexes */
  197. enum {
  198.     kSelectRegistryEntryIDInit    = 0,
  199.     kSelectRegistryEntryIDCompare = 1,
  200.     kSelectRegistryEntryIDCopy    = 2,
  201.     kSelectRegistryEntryIDDispose = 3,
  202.     kSelectRegistryCStrEntryCreate = 4,
  203.     kSelectRegistryEntryDelete    = 5,
  204.     kSelectRegistryEntryCopy    = 6,
  205.     kSelectRegistryEntryIterateCreate = 7,
  206.     kSelectRegistryEntryIterateDispose = 8,
  207.     kSelectRegistryEntryIterateSet = 9,
  208.     kSelectRegistryEntryIterate    = 10,
  209.     kSelectRegistryEntrySearch    = 11,
  210.     kSelectRegistryCStrEntryLookup = 12,
  211.     kSelectRegistryEntryToPathSize = 13,
  212.     kSelectRegistryCStrEntryToPath = 14,
  213.     kSelectRegistryCStrEntryToName = 15,
  214.     kSelectRegistryPropertyCreate = 16,
  215.     kSelectRegistryPropertyDelete = 17,
  216.     kSelectRegistryPropertyRename = 18,
  217.     kSelectRegistryPropertyIterateCreate = 19,
  218.     kSelectRegistryPropertyIterateDispose = 20,
  219.     kSelectRegistryPropertyIterate = 21,
  220.     kSelectRegistryPropertyGetSize = 22,
  221.     kSelectRegistryPropertyGet    = 23,
  222.     kSelectRegistryPropertySet    = 24,
  223.     kSelectRegistryEntryGetMod    = 25,
  224.     kSelectRegistryEntrySetMod    = 26,
  225.     kSelectRegistryPropertyGetMod = 27,
  226.     kSelectRegistryPropertySetMod = 28,
  227.     kSelectRegistryEntryMod        = 29,
  228.     kSelectRegistryEntryPropertyMod = 30,                        /* if you add more selectors here, remember to change 'kSelectRegistryHighestSelector' below*/
  229.     kSelectRegistryHighestSelector = kSelectRegistryEntryPropertyMod
  230. };
  231.  
  232.  
  233. /* ///////////////////////
  234. //
  235. // Entry Management
  236. //
  237. /////////////////////// */
  238.  
  239. /*-------------------------------
  240.  * EntryID handling
  241.  */
  242. /*
  243.  * Initialize an EntryID to a known invalid state
  244.  *   note: invalid != uninitialized
  245.  */
  246. EXTERN_API_C( OSStatus )
  247. RegistryEntryIDInit                (RegEntryID *            id)                                    TWOWORDINLINE(0x7000, 0xABE9);
  248.  
  249. /*
  250.  * Compare EntryID's for equality or if invalid
  251.  *
  252.  * If a NULL value is given for either id1 or id2, the other id 
  253.  * is compared with an invalid ID.  If both are NULL, the id's 
  254.  * are consided equal (result = true). 
  255.  */
  256. EXTERN_API_C( Boolean )
  257. RegistryEntryIDCompare            (const RegEntryID *        id1,
  258.                                  const RegEntryID *        id2)                                TWOWORDINLINE(0x7001, 0xABE9);
  259.  
  260. /*
  261.  * Copy an EntryID
  262.  */
  263. EXTERN_API_C( OSStatus )
  264. RegistryEntryIDCopy                (const RegEntryID *        src,
  265.                                  RegEntryID *            dst)                                TWOWORDINLINE(0x7002, 0xABE9);
  266.  
  267. /*
  268.  * Free an ID so it can be reused.
  269.  */
  270. EXTERN_API_C( OSStatus )
  271. RegistryEntryIDDispose            (RegEntryID *            id)                                    TWOWORDINLINE(0x7003, 0xABE9);
  272.  
  273. /*-------------------------------
  274.  * Adding and removing entries
  275.  *
  276.  * If (parentEntry) is NULL, the name is assumed
  277.  * to be a rooted path. It is rooted to an anonymous, unnamed root.
  278.  */
  279. EXTERN_API_C( OSStatus )
  280. RegistryCStrEntryCreate            (const RegEntryID *        parentEntry,
  281.                                  const RegCStrPathName * name,
  282.                                  RegEntryID *            newEntry)                            TWOWORDINLINE(0x7004, 0xABE9);
  283.  
  284. EXTERN_API_C( OSStatus )
  285. RegistryEntryDelete                (const RegEntryID *        id)                                    TWOWORDINLINE(0x7005, 0xABE9);
  286.  
  287. EXTERN_API_C( OSStatus )
  288. RegistryEntryCopy                (RegEntryID *            parentEntryID,
  289.                                  RegEntryID *            sourceDevice,
  290.                                  RegEntryID *            destDevice)                            TWOWORDINLINE(0x7006, 0xABE9);
  291.  
  292. /*---------------------------
  293.  * Traversing the namespace
  294.  *
  295.  * To support arbitrary namespace implementations in the future,
  296.  * I have hidden the form that the place pointer takes.  The previous
  297.  * interface exposed the place pointer by specifying it as a
  298.  * RegEntryID.
  299.  *
  300.  * I have also removed any notion of returning the entries
  301.  * in a particular order, because an implementation might
  302.  * return the names in semi-random order.  Many name service
  303.  * implementations will store the names in a hashed lookup
  304.  * table.
  305.  *
  306.  * Writing code to traverse some set of names consists of
  307.  * a call to begin the iteration, the iteration loop, and
  308.  * a call to end the iteration.  The begin call initializes
  309.  * the iteration cookie data structure.  The call to end the 
  310.  * iteration should be called even in the case of error so 
  311.  * that allocated data structures can be freed.
  312.  *
  313.  *    Create(...)
  314.  *    do {
  315.  *        Iterate(...);
  316.  *    } while (!done);
  317.  *    Dispose(...);
  318.  *
  319.  * This is the basic code structure for callers of the iteration
  320.  * interface.
  321.  */
  322. typedef struct OpaqueRegEntryIter*         RegEntryIter;
  323. /* 
  324.  * create/dispose the iterator structure
  325.  *   defaults to root with relationship = kRegIterDescendants
  326.  */
  327. EXTERN_API_C( OSStatus )
  328. RegistryEntryIterateCreate        (RegEntryIter *            cookie)                                TWOWORDINLINE(0x7007, 0xABE9);
  329.  
  330. EXTERN_API_C( OSStatus )
  331. RegistryEntryIterateDispose        (RegEntryIter *            cookie)                                TWOWORDINLINE(0x7008, 0xABE9);
  332.  
  333. /* 
  334.  * set Entry Iterator to specified entry
  335.  */
  336. EXTERN_API_C( OSStatus )
  337. RegistryEntryIterateSet            (RegEntryIter *            cookie,
  338.                                  const RegEntryID *        startEntryID)                        TWOWORDINLINE(0x7009, 0xABE9);
  339.  
  340. /*
  341.  * Return each value of the iteration
  342.  *
  343.  * return entries related to the current entry
  344.  * with the specified relationship
  345.  */
  346. EXTERN_API_C( OSStatus )
  347. RegistryEntryIterate            (RegEntryIter *            cookie,
  348.                                  RegEntryIterationOp     relationship,
  349.                                  RegEntryID *            foundEntry,
  350.                                  Boolean *                done)                                TWOWORDINLINE(0x700A, 0xABE9);
  351.  
  352. /*
  353.  * return entries with the specified property
  354.  *
  355.  * A NULL RegPropertyValue pointer will return an
  356.  * entry with the property containing any value.
  357.  */
  358. EXTERN_API_C( OSStatus )
  359. RegistryEntrySearch                (RegEntryIter *            cookie,
  360.                                  RegEntryIterationOp     relationship,
  361.                                  RegEntryID *            foundEntry,
  362.                                  Boolean *                done,
  363.                                  const RegPropertyName * propertyName,
  364.                                  const void *            propertyValue,
  365.                                  RegPropertyValueSize     propertySize)                        TWOWORDINLINE(0x700B, 0xABE9);
  366.  
  367. /*--------------------------------
  368.  * Find a name in the namespace
  369.  *
  370.  * This is the fast lookup mechanism.
  371.  * NOTE:  A reverse lookup mechanism
  372.  *      has not been provided because
  373.  *        some name services may not
  374.  *        provide a fast, general reverse
  375.  *        lookup.
  376.  */
  377. EXTERN_API_C( OSStatus )
  378. RegistryCStrEntryLookup            (const RegEntryID *        searchPointID,
  379.                                  const RegCStrPathName * pathName,
  380.                                  RegEntryID *            foundEntry)                            TWOWORDINLINE(0x700C, 0xABE9);
  381.  
  382. /*---------------------------------------------
  383.  * Convert an entry to a rooted name string
  384.  *
  385.  * A utility routine to turn an Entry ID
  386.  * back into a name string.
  387.  */
  388. EXTERN_API_C( OSStatus )
  389. RegistryEntryToPathSize            (const RegEntryID *        entryID,
  390.                                  RegPathNameSize *        pathSize)                            TWOWORDINLINE(0x700D, 0xABE9);
  391.  
  392. EXTERN_API_C( OSStatus )
  393. RegistryCStrEntryToPath            (const RegEntryID *        entryID,
  394.                                  RegCStrPathName *        pathName,
  395.                                  RegPathNameSize         pathSize)                            TWOWORDINLINE(0x700E, 0xABE9);
  396.  
  397. /*
  398.  * Parse a path name.
  399.  *
  400.  * Retrieve the last component of the path, and
  401.  * return a spec for the parent.
  402.  */
  403. EXTERN_API_C( OSStatus )
  404. RegistryCStrEntryToName            (const RegEntryID *        entryID,
  405.                                  RegEntryID *            parentEntry,
  406.                                  RegCStrEntryName *        nameComponent,
  407.                                  Boolean *                done)                                TWOWORDINLINE(0x700F, 0xABE9);
  408.  
  409. /* //////////////////////////////////////////////////////
  410. //
  411. // Property Management
  412. //
  413. ////////////////////////////////////////////////////// */
  414. /*-------------------------------
  415.  * Adding and removing properties
  416.  */
  417. EXTERN_API_C( OSStatus )
  418. RegistryPropertyCreate            (const RegEntryID *        entryID,
  419.                                  const RegPropertyName * propertyName,
  420.                                  const void *            propertyValue,
  421.                                  RegPropertyValueSize     propertySize)                        TWOWORDINLINE(0x7010, 0xABE9);
  422.  
  423. EXTERN_API_C( OSStatus )
  424. RegistryPropertyDelete            (const RegEntryID *        entryID,
  425.                                  const RegPropertyName * propertyName)                        TWOWORDINLINE(0x7011, 0xABE9);
  426.  
  427. EXTERN_API_C( OSStatus )
  428. RegistryPropertyRename            (const RegEntryID *        entry,
  429.                                  const RegPropertyName * oldName,
  430.                                  const RegPropertyName * newName)                            TWOWORDINLINE(0x7012, 0xABE9);
  431.  
  432. /*---------------------------
  433.  * Traversing the Properties of a name
  434.  *
  435.  */
  436. typedef struct OpaqueRegPropertyIter*     RegPropertyIter;
  437. EXTERN_API_C( OSStatus )
  438. RegistryPropertyIterateCreate    (const RegEntryID *        entry,
  439.                                  RegPropertyIter *        cookie)                                TWOWORDINLINE(0x7013, 0xABE9);
  440.  
  441. EXTERN_API_C( OSStatus )
  442. RegistryPropertyIterateDispose    (RegPropertyIter *        cookie)                                TWOWORDINLINE(0x7014, 0xABE9);
  443.  
  444. EXTERN_API_C( OSStatus )
  445. RegistryPropertyIterate            (RegPropertyIter *        cookie,
  446.                                  RegPropertyName *        foundProperty,
  447.                                  Boolean *                done)                                TWOWORDINLINE(0x7015, 0xABE9);
  448.  
  449. /*
  450.  * Get the value of the specified property for the specified entry.
  451.  *
  452.  */
  453. EXTERN_API_C( OSStatus )
  454. RegistryPropertyGetSize            (const RegEntryID *        entryID,
  455.                                  const RegPropertyName * propertyName,
  456.                                  RegPropertyValueSize *    propertySize)                        TWOWORDINLINE(0x7016, 0xABE9);
  457.  
  458. /*
  459.  * (*propertySize) is the maximum size of the value returned in the buffer
  460.  * pointed to by (propertyValue).  Upon return, (*propertySize) is the size of the
  461.  * value returned.
  462.  */
  463. EXTERN_API_C( OSStatus )
  464. RegistryPropertyGet                (const RegEntryID *        entryID,
  465.                                  const RegPropertyName * propertyName,
  466.                                  void *                    propertyValue,
  467.                                  RegPropertyValueSize *    propertySize)                        TWOWORDINLINE(0x7017, 0xABE9);
  468.  
  469. EXTERN_API_C( OSStatus )
  470. RegistryPropertySet                (const RegEntryID *        entryID,
  471.                                  const RegPropertyName * propertyName,
  472.                                  const void *            propertyValue,
  473.                                  RegPropertyValueSize     propertySize)                        TWOWORDINLINE(0x7018, 0xABE9);
  474.  
  475. /* //////////////////////////////////////////////////////
  476. //
  477. // Modifier Management
  478. //
  479. ////////////////////////////////////////////////////// */
  480. /*
  481.  * Modifiers describe special characteristics of names
  482.  * and properties.  Modifiers might be supported for
  483.  * some names and not others.
  484.  * 
  485.  * Device Drivers should not rely on functionality
  486.  * specified as a modifier.  These interfaces
  487.  * are for use in writing Experts.
  488.  */
  489. /*
  490.  * Get and Set operators for entry modifiers
  491.  */
  492. EXTERN_API_C( OSStatus )
  493. RegistryEntryGetMod                (const RegEntryID *        entry,
  494.                                  RegEntryModifiers *    modifiers)                            TWOWORDINLINE(0x7019, 0xABE9);
  495.  
  496. EXTERN_API_C( OSStatus )
  497. RegistryEntrySetMod                (const RegEntryID *        entry,
  498.                                  RegEntryModifiers         modifiers)                            TWOWORDINLINE(0x701A, 0xABE9);
  499.  
  500. /*
  501.  * Get and Set operators for property modifiers
  502.  */
  503. EXTERN_API_C( OSStatus )
  504. RegistryPropertyGetMod            (const RegEntryID *        entry,
  505.                                  const RegPropertyName * name,
  506.                                  RegPropertyModifiers *    modifiers)                            TWOWORDINLINE(0x701B, 0xABE9);
  507.  
  508. EXTERN_API_C( OSStatus )
  509. RegistryPropertySetMod            (const RegEntryID *        entry,
  510.                                  const RegPropertyName * name,
  511.                                  RegPropertyModifiers     modifiers)                            TWOWORDINLINE(0x701C, 0xABE9);
  512.  
  513. /*
  514.  * Iterator operator for entry modifier search
  515.  */
  516. EXTERN_API_C( OSStatus )
  517. RegistryEntryMod                (RegEntryIter *            cookie,
  518.                                  RegEntryIterationOp     relationship,
  519.                                  RegEntryID *            foundEntry,
  520.                                  Boolean *                done,
  521.                                  RegEntryModifiers         matchingModifiers)                    TWOWORDINLINE(0x701D, 0xABE9);
  522.  
  523. /*
  524.  * Iterator operator for entries with matching 
  525.  * property modifiers
  526.  */
  527. EXTERN_API_C( OSStatus )
  528. RegistryEntryPropertyMod        (RegEntryIter *            cookie,
  529.                                  RegEntryIterationOp     relationship,
  530.                                  RegEntryID *            foundEntry,
  531.                                  Boolean *                done,
  532.                                  RegPropertyModifiers     matchingModifiers)                    TWOWORDINLINE(0x701E, 0xABE9);
  533.  
  534.  
  535.  
  536. #if PRAGMA_STRUCT_ALIGN
  537.     #pragma options align=reset
  538. #elif PRAGMA_STRUCT_PACKPUSH
  539.     #pragma pack(pop)
  540. #elif PRAGMA_STRUCT_PACK
  541.     #pragma pack()
  542. #endif
  543.  
  544. #ifdef PRAGMA_IMPORT_OFF
  545. #pragma import off
  546. #elif PRAGMA_IMPORT
  547. #pragma import reset
  548. #endif
  549.  
  550. #ifdef __cplusplus
  551. }
  552. #endif
  553.  
  554. #endif /* __NAMEREGISTRY__ */
  555.  
  556.